home *** CD-ROM | disk | FTP | other *** search
/ BBS in a Box 5 / BBS in a Box -Volume V (BBS in a Box) (April 1992).iso / Files / Apple / Apple II TNs(Text).cpt / Apple II TNs(Text) / IIGS / TN.IIGS.053 / TN.IIGS.053
Encoding:
Text File  |  1989-11-15  |  11.6 KB  |  235 lines  |  [TEXT/pdos]
  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5. Apple IIGS
  6. #53:    Desk Accessories and Tools
  7.  
  8. Written by:    Matt Deatherage & Jim Mensch                        March 1989
  9.  
  10. This Technical Note describes new guidelines for developers to help 
  11. applications and desk accessories live together in the same system at the same 
  12. time.
  13. _____________________________________________________________________________
  14.  
  15.  
  16. Introduction
  17.  
  18. Desk accessories vary widely in complexity.  Classic Desk Accessories (CDAs) 
  19. range from simple status-reporting programs to complete system-level debugging 
  20. utilities, and similarly, New Desk Accessories (NDAs) range from static 
  21. windows with pictures to nearly full-fledged applications.
  22.  
  23. This Note presents some new guidelines aimed at helping developers of both 
  24. applications and desk accessories to get their products to work together now 
  25. and in the future.
  26.  
  27.  
  28. Tool Sets
  29.  
  30. The greatest current conflict between applications and desk accessories, 
  31. especially NDAs, is the use of system tool sets.  The Apple IIGS Toolbox 
  32. Reference, Volume 1, defines which tools are available for use by NDAs.  The 
  33. Desk Manager requires starting the following tool sets before calling 
  34. FixAppleMenu (which installs the names of the NDAs in the Apple menu):
  35.  
  36.     Tool Locator (#1)
  37.     Memory Manager (#2)
  38.     Miscellaneous Tools (#3)
  39.     QuickDraw II (#4)
  40.     Event Manager (#5)
  41.     Window Manager (#14)
  42.     Menu Manager (#15)
  43.     Control Manager (#16)
  44.     LineEdit (#20)
  45.     Dialog Manager (#21)
  46.     Scrap Manager (#22)
  47.  
  48. Since the Desk Manager requires starting these tools before calling 
  49. FixAppleMenu, NDAs may assume that these tools are all present and running, so 
  50. they do not need to check for their presence.  
  51.  
  52. In addition to these requirements by the Desk Manager, Apple II Developer 
  53. Technical Support strongly recommends that all applications start the 
  54. following tools:
  55.  
  56.     QuickDraw Auxiliary (#16)
  57.     Font Manager (#27)
  58.  
  59. These two additional tools are so widely used by desk accessories that they 
  60. should be present.  An NDA may not assume their presence, but any application 
  61. that calls FixAppleMenu should also start these two tools.
  62.  
  63.  
  64. The Golden NDA Guideline
  65.  
  66. Developers who wish to maintain maximum compatibility between their NDAs and 
  67. applications, both now and in the future, should consider every environment 
  68. change they make with the following Golden NDA Guideline firmly in mind:
  69.  
  70.     "I, an NDA, pledge not to alter the environment of the application 
  71.     under which I run, and I will behave in such a way that the 
  72.     application runs the same whether I am present or not."
  73.  
  74. Of course, this guideline does not include such necessary tasks as the normal 
  75. (and reasonable) allocation of memory.  An application must be prepared to 
  76. handle a memory allocation call by a desk accessory, operating system, or even 
  77. a tool at unexpected times.  The guideline does, however, mean that your desk 
  78. accessory cannot change the operating environment, including such things as 
  79. the presence of tools and operating system parameters.  The following sections 
  80. detail some of the most important ways of following the Golden NDA Guideline.
  81.  
  82.  
  83. Desk Accessory Guidelines
  84.  
  85. Extra Tools
  86.  
  87. o    If an NDA wishes to use a tool which is not available in the standard 
  88.      list (e.g., Standard File), it should check to see if the tool is 
  89.      already running.  If it is not running, the NDA must use LoadOneTool to 
  90.      load it, then it must start the tool before using it.  When finished 
  91.      with the tool, the NDA must shut it down and unload it with 
  92.      UnloadOneTool.
  93.  
  94. o    If an NDA wishes to use a tool which is not available in the standard 
  95.      list and the NDA wants to use it in a non-modal fashion, then it has 
  96.      even more work to do.  In addition to the conditions set for a tool 
  97.      which is not available in the standard list, if your NDA uses a tool in 
  98.      a non-modal fashion, you must shut it down and unload it when your 
  99.      window is deactivated.
  100.  
  101.      The Golden NDA Guideline shows why this is true.  If your NDA started a 
  102.      tool which the application was going to use but had not yet started 
  103.      (i.e., the Font Manager), and your NDA does not shut it down when the 
  104.      application takes control of the system, the application will get error 
  105.      $1B01 (Font Manager Already Started) when it makes the FMStartUp call, 
  106.      and this error can cause the application to fail.
  107.  
  108.      Therefore, when your window is deactivated, if you shut down all the 
  109.      tools you have started, the application will be free to start those 
  110.      tools which it requires.  When your window is reactivated, you must 
  111.      check the status of each tool in question then reload and restart those 
  112.      which are not present before reusing them.
  113.  
  114.      In this case, the Golden NDA Guideline means that an application must 
  115.      not be forced to check the status of a tool which it has not started.  
  116.      Applications are not required to do so, and most of them do not.
  117.  
  118. o    Sound tools provide the one exception to the rule of freely using a 
  119.      tool which is already started.  Refer to the section on System 
  120.      Parameters for more details on using sound tools.
  121.  
  122. o    An NDA must not shut down tools which it has not started.  If you 
  123.      start a tool then shut it down when finished with it, you must be sure 
  124.      not to accidently shut it down the next time your window is deactivated.
  125.  
  126. o    A CDA is nearly always modal, but it has the capability to install 
  127.      HeartBeat Tasks and other ways of being called after returning to an 
  128.      application (which could be running under ProDOS 8).  If a CDA installs 
  129.      a method of performing tasks after the user has returned to the 
  130.      application, it must be careful not to use any tools which are not 
  131.      started, since the list of available tools for NDAs does not hold true 
  132.      for CDAs.
  133.  
  134. System Parameters
  135.  
  136. o    A desk accessory (CDA or NDA) must not change a system resource or 
  137.      parameter which cannot be restored to its original condition.  A 
  138.      trivial, but illustrative, example of this is the number of times a 
  139.      pull-down menu item blinks when you select it.  This number (three by 
  140.      default) may be changed with the SetMItemBlink call, but there is not 
  141.      corresponding GetMItemBlink call, so you cannot retrieve the current 
  142.      value.  Therefore, a desk accessory must not change this parameter, and 
  143.      the same rule applies to any other system parameter for which you cannot 
  144.      determine a current value.
  145.  
  146. o    This idea extends to calling tool startup functions.  Even if a tool's 
  147.      startup function does not return an error if the tool is already active, 
  148.      it may reset certain parameters upon which the application depends.  An 
  149.      example of this is TLStartUp for the Tool Locator.  A seemingly 
  150.      innocuous call, TLStartUp actually disconnects any user tool sets 
  151.      present, which, in this case, would most likely have been installed by 
  152.      the current application.
  153.  
  154.      A desk accessory should not call any tool's startup function if the 
  155.      tool is already active.  The one exception to this rule is the Memory 
  156.      Manager's MMStartUp call, which a desk accessory may make to obtain its 
  157.      User ID.  MMStartUp may be considered equivalent to a GetMyID call.
  158.  
  159. o    A desk accessory cannot use any of the sound tools if they are 
  160.      already started.  This is contrary to all other tool sets, but it is 
  161.      required in this case since there is no memory management of the sound 
  162.      RAM.  If the Sound Tools (#8) are started, the application has exclusive 
  163.      control of the 64K DOC RAM used to play sounds.  Anything your desk 
  164.      accessory might put there is likely to overwrite information the 
  165.      application needs.
  166.  
  167.      Saving and restoring DOC RAM around desk accessory usage is not 
  168.      sufficient.  Many of the sound functions are interrupt-driven, altering 
  169.      the contents of DOC RAM only at sound interrupts, so your desk accessory 
  170.      might attempt to replace parts of DOC RAM which are being played.  Since 
  171.      there is no memory management of DOC RAM, desk accessories must avoid 
  172.      the sound functions of the IIGS if the application is already using 
  173.      them.
  174.  
  175. o    A desk accessory must not install user tool sets, because there is no 
  176.      arbitration of user tool set numbers.
  177.  
  178.  
  179. Application Guidelines
  180.  
  181. To coexist peacefully with desk accessories, particularly NDAs, applications 
  182. generally need to follow the guidelines listed in the Desk Manager chapter of 
  183. the Apple IIGS Toolbox Reference, Volume 1.  However, those applications which 
  184. wish to ensure maximum compatibility now and in the future will also want to 
  185. adhere to the following:
  186.  
  187. o    Don't just start the Scrap Manager--use it.  Many desk accessories are 
  188.      capable of cutting and pasting information between themselves and your 
  189.      application, but they cannot do so if you do not use the Scrap Manager.  
  190.      If you handle the Edit menu functions privately, without placing the 
  191.      information on your internal clipboard in the public scrap, a desk 
  192.      accessory will not be able to access it.  This inability to share 
  193.      information frustrates both the users and the developers who write desk 
  194.      accessories.
  195.  
  196. o    Start tools at the beginning of your application and leave them 
  197.      started.  Every time you call SystemTask or TaskMaster, a desk accessory 
  198.      might take control of the system, and if your application has shut down 
  199.      a tool that a desk accessory found running and is using, it might not be 
  200.      able to complete an operation.  For example, a desk accessory might be 
  201.      using the Print Manager, having found it started by your application.  
  202.      If your application takes control of the system and shuts down the Print 
  203.      Manager while the desk accessory is printing a document, the desk 
  204.      accessory will not be able to finish when it regains control.
  205.  
  206.      For maximum compatibility, do not shut down any tools which were ever 
  207.      active when you called SystemTask or TaskMaster.  You can start more 
  208.      tools, but do not shut down those which are already active.  If you 
  209.      intend to start a tool and not keep it started, use it then shut it down 
  210.      immediately, being sure not to call SystemTask or TaskMaster during that 
  211.      time.
  212.  
  213. o    An application with some memory to spare can save NDAs time by 
  214.      providing them the additional tools which they are most likely to use.  
  215.      If a desk accessory wishes to use the List Manager and your application 
  216.      starts it, the desk accessory will naturally run faster since it will 
  217.      succeed on the ListStatus call every time and can avoid loading and 
  218.      starting the tool on every activation.
  219.  
  220.      The most common tools which desk accessories require besides those 
  221.      available in the standard Desk Manager set are QuickDraw Auxiliary 
  222.      (#16), the Print Manager (#19), Standard File (#24), the Font Manager 
  223.      (#27), and the List Manager (#28).  QuickDraw Auxiliary and the Font 
  224.      Manager are especially important--not only do they work well together, 
  225.      but they are also widely used.  In addition, FMStartUp can take a long 
  226.      time, and waiting for it every time you activate an NDA window gets 
  227.      really frustrating.  Many desk accessories also use the Print Manager, 
  228.      the List Manager, and Standard File, and if they are always available, 
  229.      desk accessories will work more smoothly with your application.
  230.  
  231.  
  232. Further Reference:
  233. _____________________________________________________________________________
  234.     o    Apple IIGS Toolbox Reference, Volume 1
  235.     o    Programmer's Introduction to the Apple IIGS